Skip to content

migrate warp.md to agents.md and improve it #741

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 1 commit into from
Sep 18, 2025
Merged

migrate warp.md to agents.md and improve it #741

merged 1 commit into from
Sep 18, 2025

Conversation

@KRRT7
Copy link
Contributor

@KRRT7 KRRT7 commented Sep 18, 2025 •
edited by github-actions bot
Loading

PR Type

Documentation

Description

  • Add comprehensive AGENTS.md for AI agents

  • Replace and remove outdated WARP.md

  • Detail architecture, workflows, commands

  • Standardize dev practices and tooling

Diagram Walkthrough

flowchart LR
  W["WARP.md (Warp-specific guide)"] -- "removed" --> X["Deleted"]
  A["AGENTS.md (Agent-agnostic guide)"] -- "added" --> Repo["Repository Docs"]
  A -- "covers" --> Arch["Architecture & Workflows"]
  A -- "details" --> Dev["Dev setup & commands"]
  A -- "defines" --> Patterns["Best practices & patterns"]
Loading

File Walkthrough
Relevant files
Documentation
AGENTS.md
Add comprehensive AI agent instructions                                   

AGENTS.md

  • Add agent-agnostic guidance for CodeFlash
  • Document architecture, workflows, and components
  • Provide commands, configs, and best practices
  • Specify testing, tooling, and telemetry usage
 +318/-0 
WARP.md
Remove outdated Warp guide                                                             

WARP.md

  • Remove Warp-specific guidance document
  • Superseded by new AGENTS.md
 +0/-191 

@github-actions
Copy link

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Consistency

The doc mandates using uv exclusively and libcst over ast; verify the rest of the repo and automation (CI, scripts, Makefiles, pre-commit, README) are aligned to avoid contradictory guidance.

 
```bash
# Always use uv, never pip
uv sync                    # Install dependencies
uv sync --group dev        # Install dev dependencies
uv run pytest              # Run commands
uv add package             # Add new packages
uv build                   # Build package

Code Manipulation with LibCST (NOT ast)

Always use libcst for code parsing/modification to preserve formatting:

from libcst import parse_module, PartialPythonCodeGen
# Never use ast module for code transformations

Testing with Deterministic Execution

Custom pytest plugin (codeflash/verification/pytest_plugin.py) ensures reproducible tests:


</details>

<details><summary><a href='https://github.com/codeflash-ai/codeflash/pull/741/files#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9R246-R255'><strong>Accuracy</strong></a>

Some paths/modules may be outdated or renamed (e.g., telemetry modules, ai service path, pytest plugin location). Cross-check that all referenced files and commands exist to prevent dead links.
</summary>

```markdown
### Rate Limiting & Retries
- Built-in rate limiting and exponential backoff
- Handle `Either` return types for error handling
- AI service endpoint: `codeflash/api/aiservice.py`

### Telemetry & Monitoring
- **Sentry**: Error tracking with `codeflash.telemetry.sentry`
- **PostHog**: Usage analytics with `codeflash.telemetry.posthog_cf`
- **Environment Variables**: `CODEFLASH_EXPERIMENT_ID` for testing modes
Completeness

Security, secrets handling, and configuration for external services (Sentry/PostHog/LLM keys) are not described; consider adding env var names, local dev defaults, and redaction practices.

 
- Built-in rate limiting and exponential backoff
- Handle `Either` return types for error handling
- AI service endpoint: `codeflash/api/aiservice.py`

### Telemetry & Monitoring
- **Sentry**: Error tracking with `codeflash.telemetry.sentry`
- **PostHog**: Usage analytics with `codeflash.telemetry.posthog_cf`
- **Environment Variables**: `CODEFLASH_EXPERIMENT_ID` for testing modes

@github-actions
Copy link

PR Code Suggestions ✨

No code suggestions found for the PR.

aseembits93
aseembits93 reviewed Sep 18, 2025
View reviewed changes
.gitignore

# Mac
.DS_Store
WARP.MD
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

insert newline, *.md instead of .MD

@aseembits93
Copy link
Contributor

not sure when the format will get standardized!

@KRRT7
Copy link
Contributor Author

KRRT7 commented Sep 18, 2025

not sure when the format will get standardized!

https://agents.md

basically the standard is "as long as you use agents.md for the filename, and you have markdown inside, fine with us"

@KRRT7 KRRT7 enabled auto-merge September 18, 2025 05:48
@KRRT7 KRRT7 merged commit 9fdf45f into main Sep 18, 2025
19 of 23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@aseembits93 aseembits93 aseembits93 approved these changes

@misrasaurabh1 misrasaurabh1 Awaiting requested review from misrasaurabh1

@Saga4 Saga4 Awaiting requested review from Saga4

Assignees

No one assigned

Labels

Review effort 2/5

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@KRRT7 @aseembits93